UI Service Integration And IPC Communication

1. Introduction

2. Project Structure

3. Core Components

4. Architecture Overview

5. Detailed Component Analysis

6. Dependency Analysis

7. Performance Considerations

8. Troubleshooting Guide

9. Conclusion

This document explains how the React-based UI integrates with Electron’s main process through Inter-Process Communication (IPC), how the preload script exposes secure Node.js APIs to the renderer, and how Pyodide enables browser-based Python execution. It covers message passing patterns, error handling across process boundaries, UI update coordination, and security considerations such as context isolation.

The Electron application is organized into:

• UI layer: React components under electron/src/ui and electron/src/components

• Electron main process: electron/src/electron/main.js orchestrates windows, IPC handlers, and services

• Preload bridge: electron/src/electron/preload.js exposes a controlled API surface to the renderer

• Services: Gmail and SMTP handlers under electron/src/electron

• Pyodide utilities: electron/src/utils/pyodide.js and Python scripts under electron/dist-react/py and electron/public/py

Diagram sources

• main.jsx

• App.jsx

• BulkMailer.jsx

• WhatsAppForm.jsx

• preload.js

• main.js

• gmail-handler.js

• smtp-handler.js

• pyodide.js

• parse_manual_numbers.py

Section sources

• main.jsx

• App.jsx

• BulkMailer.jsx

• WhatsAppForm.jsx

• preload.js

• main.js

• gmail-handler.js

• smtp-handler.js

• pyodide.js

• parse_manual_numbers.py

• vite.config.js

• index.html

• Electron main process: Creates the BrowserWindow with context isolation enabled, registers IPC handlers for Gmail, SMTP, and WhatsApp, and manages the WhatsApp client lifecycle.

• Preload bridge: Exposes a typed API surface to the renderer via contextBridge, wrapping ipcRenderer.invoke and ipcRenderer.on.

• React UI: BulkMailer coordinates tabs and state, wires UI events to preload APIs, and renders real-time status updates.

• Pyodide integration: Dynamically loads Pyodide and executes a Python script to parse manual phone numbers in the renderer.

Key responsibilities:

• Secure exposure of Node.js capabilities through a minimal, typed API

• Real-time status updates via event-driven IPC channels

• Controlled rate-limiting and error propagation across processes

• Browser-based Python execution for contact parsing

Section sources

• main.js

• preload.js

• BulkMailer.jsx

• pyodide.js

The UI communicates with the main process using two primary patterns:

• Request-response via ipcRenderer.invoke and ipcMain.handle for synchronous operations

• Event streaming via ipcRenderer.on and event.sender.send for progress/status updates

Diagram sources

• preload.js

• main.js

• gmail-handler.js

• gmail-handler.js

IPC Handlers and UI Coordination#

• Gmail authentication and sending:

  • Preload exposes authenticateGmail, getGmailToken, and sendEmail

  • Main registers ipcMain.handle for gmail-auth, gmail-token, and send-email

  • Gmail handler opens an OAuth window, exchanges tokens, stores credentials, and streams progress via email-progress events

• SMTP sending:

  • Preload exposes sendSMTPEmail

  • Main registers smtp-send handler that verifies transport, sends emails, and streams progress

• WhatsApp integration:

  • Preload exposes startWhatsAppClient, logoutWhatsApp, sendWhatsAppMessages, importWhatsAppContacts, and status listeners

  • Main creates a WhatsApp client with QR generation, emits status and QR events, and handles mass messaging with per-contact delays

Diagram sources

• preload.js

• main.js

• main.js

• BulkMailer.jsx

• BulkMailer.jsx

Section sources

• gmail-handler.js

• gmail-handler.js

• smtp-handler.js

• main.js

• main.js

• main.js

• preload.js

• BulkMailer.jsx

• BulkMailer.jsx

Preload Script and Security Context#

• The preload script uses contextBridge.exposeInMainWorld to publish a single API object electronAPI

• It wraps:

  • Gmail: authenticateGmail, getGmailToken, sendEmail

  • SMTP: sendSMTPEmail

  • File operations: importEmailList, readEmailListFile

  • Progress: onProgress

  • WhatsApp: startWhatsAppClient, logoutWhatsApp, sendWhatsAppMessages, importWhatsAppContacts, and three status listeners

• Security settings in BrowserWindow webPreferences:

  • nodeIntegration: false

  • contextIsolation: true

  • enableRemoteModule: false

  • webSecurity: true

  • preload path set to preload.js

Diagram sources

• preload.js

Section sources

• main.js

• preload.js

Pyodide Integration for Browser-Based Python Execution#

• The UI invokes parseManualNumbers from BulkMailer.jsx, which calls a utility in pyodide.js

• pyodide.js dynamically loads Pyodide from a CDN, initializes it, loads the Python script from the app’s built resources, and executes a function that parses phone numbers

• The Python script cleans and validates phone numbers, supports name-number pairs, and returns structured contact data

Diagram sources

• pyodide.js

• parse_manual_numbers.py

• BulkMailer.jsx

Section sources

• pyodide.js

• parse_manual_numbers.py

• parse_manual_numbers.py

• BulkMailer.jsx

UI Update Coordination and Status Streams#

• WhatsApp status and QR updates:

  • Main process emits “whatsapp-status”, “whatsapp-qr”, and “whatsapp-send-status”

  • Preload forwards these via ipcRenderer.on listeners

  • BulkMailer subscribes in useEffect and updates local state for display

• Email progress:

  • Gmail and SMTP handlers send “email-progress” events during batch operations

  • Preload exposes onProgress; BulkMailer uses it to render live progress and results

Diagram sources

• preload.js

• main.js

• gmail-handler.js

• BulkMailer.jsx

Section sources

• main.js

• gmail-handler.js

• BulkMailer.jsx

• UI depends on preload for IPC primitives and on pyodide.js for Python parsing

• Preload depends on main process handlers for all operations

• Main process handlers depend on external libraries (Google APIs, Nodemailer, WhatsApp Web)

• Build system uses Vite to bundle the UI and serve from ./dist-react

Diagram sources

• main.jsx

• preload.js

• main.js

• gmail-handler.js

• smtp-handler.js

• pyodide.js

• parse_manual_numbers.py

Section sources

• package.json

• vite.config.js

• Rate limiting: Both Gmail and SMTP handlers introduce delays between emails to avoid throttling and respect provider limits

• Batch processing: WhatsApp sends messages with deliberate pauses to prevent rate limits and improve reliability

• Resource cleanup: Main process deletes cached WhatsApp files on logout and app close to free disk space and avoid stale sessions

• UI responsiveness: Event-driven updates keep the UI responsive while long-running tasks execute in the main process

[No sources needed since this section provides general guidance]

Common issues and resolutions:

• Electron API not available in renderer:

  • Ensure preload is correctly injected via webPreferences.preload and that the app is running in Electron (not a static HTML page)

• Gmail authentication failures:

  • Verify environment variables for client ID and secret; check OAuth redirect URI and timeouts

• SMTP connection errors:

  • Confirm host/port/credentials; note that TLS verification is disabled for self-signed certs

• WhatsApp QR loading failures:

  • Retry initialization; check console for QR generation errors; ensure headless mode Puppeteer arguments are valid

• Pyodide load failures:

  • Confirm the Python script is bundled and reachable at the expected path; check network connectivity for CDN load

Section sources

• main.js

• gmail-handler.js

• gmail-handler.js

• smtp-handler.js

• main.js

• pyodide.js

The application achieves secure UI-service integration by isolating the renderer, exposing a minimal IPC API via preload, and delegating sensitive operations to the main process. Real-time status and progress are delivered through event channels, while Pyodide enables robust contact parsing directly in the browser. Adhering to the documented patterns ensures reliable, maintainable, and secure inter-process communication.